Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

Progress Functions

Compressors and decompressors call progress functions to report on their progress in the current operation. When a component calls your progress function, it supplies you with a number that indicates the completion percentage. This fixed-point value may range from 0.0 through 1.0. Your program can cause the component to terminate the current operation by returning a result code of codecAbortErr .

The Image Compression Manager calls your progress function only during long operations, and it does not call your function more than 30 times per second.

The ProgressProcPtr data type defines a pointer to a progress function. You assign a progress function to an image or a sequence by passing a pointer to a structure that identifies the progress function to the appropriate function.

/* progress function structure */
typedef struct ICMProgressProcRecord ICMProgressProcRecord;             
typedef ICMProgressProcRecord *ICMProgressProcRecordPtr;

The progress function structure contains the following fields:

struct ICMProgressProcRecord
{
    ICMProgressUPP progressProc;            /* ptr to progress function */
    long                progressRefCon;/* reference constant */
};
progressProc
Contains a pointer to your progress function.
progressRefCon
Contains a reference constant for use by your progress function.

MyProgressProc

Your progress function should have the following form:

pascal OSErr MyProgressProc (short message, Fixed completeness,
                                         long refcon);
message
Indicates why the Image Compression Manager called your function. The following values are valid:
codecProgressOpen
Indicates the start of a long operation. This is always the first message sent to your function. Your function can use this message to trigger the display of your progress window.
codecProgressUpdatePercent
Passes completion information to your function. The Image Compression Manager repeatedly sends this message to your function. The completeness parameter indicates the relative completion of the operation. You can use this value to update your progress window.
codecProgressClose
Indicates the end of a long operation. This is always the last message sent to your function. Your function can use this message as an indication to remove its progress window.
completeness
Contains a fixed-point value indicating how far the operation has progressed. Its value is always between 0.0 and 1.0. This parameter is valid only when the message field is set to codecProgressUpdatePercent .
refcon
Contains a reference constant value for use by your progress function. Your application specifies the value of this reference constant in the progress function structure you pass to the Image Compression Manager.

DESCRIPTION

The following functions have parameters that allow you to provide application-defined progress functions: FCompressImage , FDecompressImage , TrimImage , FCompressPicture , FCompressPictureFile , DrawPictureFile , DrawTrimmedPicture , DrawTrimmedPictureFile , MakeThumbNailFromPicture , MakeThumbnailFromPictureFile , MakeThumbnailFromPixMap , SetCompressedPixMapInfo , and GetCompressedPixMapInfo . If you pass a value of -1 in the progressProc parameter of any of these functions, you obtain a standard progress function.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

codecAbortErr

-8967

Operation aborted by the progress function

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next